home *** CD-ROM | disk | FTP | other *** search
/ System Booster / System Booster.iso / Texteditors / Origami / AmigaDocs / README.AREXX < prev    next >
Text File  |  1996-09-26  |  7KB  |  178 lines
  1.  
  2. The Origami editor has an Arexx Port (it did take a long time, but now
  3. it is ready ...  in a small version).
  4.  
  5. This part of the manual describes the arexx features for the amiga port.
  6. It is the first time Arexx is supported, so there may be some bugs in
  7. it.  Please report them !!!
  8.  
  9. The port has not all the features i would like to have, but i am working
  10. on it.  See the coming features in the last section of this manual.
  11.  
  12. {{{  Definition of the Arexx features
  13. 1. Definition of the Arexx features
  14.  
  15. The port has only some predefined Arexx commands, so you have to define
  16. all features you need in the binding files.
  17.  
  18. To add an additional command, you have to do two things :
  19. - add the macro defining all commands that shall be executed
  20.   (take the macro definitions in the /bindings/fun/* files as examples)
  21. - add a os-extension line with the following syntax :
  22.   (os-extension ("AREXX " <name of the arexx command>",  <name of the macro>))
  23.   You have to replace the <name of the arexx command> with the name, that
  24.   you have to send to execute the macro named <name of the macro> defined
  25.   in the first step.
  26.   REMEMBER : You have to use the EXACT syntax as specified above, including :
  27.              - the " characters
  28.              - exactly one space between the " and the
  29.                <name of the arexx command>
  30.              - at least two spaces between the ", sequence and the
  31.                <name of the macro>
  32. REMEMBER : You have to declare a macro before(!) you use it in the
  33.            os-extension line.
  34.  
  35. See the example of the letsbeep command in the amiga.keys file.
  36.  
  37. See the OSamiga.awk script for an easier use of the AREXX port using the
  38. AWK language.
  39. }}}
  40.  
  41. {{{  Starting Origami with Arexx Port
  42. 2. Starting Origami with Arexx Port
  43.  
  44. If you want to use the AREXX features of the origami, you have to
  45. - define AREXX during compilation (the version in src/amiga/bin has
  46.   been compiled that way !)
  47. - start origami with the option -XA[REXX][=<port name>]
  48.   (the parts in brackets [] can be specified, but are not needed)
  49.   If you just use -XA or -XAREXX origami will use ORIGAMI as basename;
  50.   if you specify a portname (behind a = character), origami will use
  51.   this name as basename.
  52.   Origami will try to open a port with the basename as portname.  If
  53.   this is impossible, origami will try <basename>1, <basename>2 ...
  54.   <basename>9
  55. }}}
  56.  
  57. {{{  Calling a arexx command
  58. 3. Calling a arexx command
  59.  
  60. You can call an origami arexx command with the
  61.              address <PORTNAME> <command name>
  62. arexx command. See your Arexx description or the src/amiga/rexx/test.rexx
  63. example for more information.
  64. }}}
  65.  
  66. {{{  Passing arguments
  67. 4. Passing arguments
  68.  
  69. If you want to use arguments in your macros (see next section), you have
  70. two possible ways to pass them :
  71. a) One argument can be passed be specifying it directly behind the command
  72.            address <portname> <command> <argument>
  73. b) If you need more arguments you must use another way of passing :
  74.    You can put one argument on the stack by calling the PUTARG command
  75.            address <portname> PUTARG <argument>
  76.  
  77. Example :
  78.    You have a command --- named "message" --- that needs one argument :
  79.            address ORIGAMI message "This is a testmessage"
  80.    or
  81.            address ORIGAMI putarg "This is a testmessage"
  82.            address ORIGAMI message
  83.    See examples test2.rexx and test3.rexx
  84.  
  85. Example :
  86.    You have a command --- named "saserror" --- that needs three arguments :
  87.            address ORIGAMI putarg filename
  88.            address ORIGAMI putarg linenumber
  89.            address ORIGAMI saserror message
  90.    or
  91.            address ORIGAMI putarg filename
  92.            address ORIGAMI putarg linenumber
  93.            address ORIGAMI putarg message
  94.            address ORIGAMI saserror
  95.  
  96. REMEMBER : arguments will not be deleted from the stack, so if you would
  97.            call message without argument, the last argument from the stack
  98.            will be used.
  99. REMEMBER : the results returned by a command will be put on the stack too.
  100. }}}
  101.  
  102. {{{  Using arguments in macros
  103. 5. Using arguments in macros
  104.  
  105. If you want to write your own macros, that need arguments, you have to
  106. use the history names "arexx" for receiving the arguments.
  107. Each argument send to origami (e.g. by PUTARG) will be put in the
  108. "arexx" history, so you can get the arguments by the "history arexx"
  109. or the "get-history arexx <offset>" commands (see examples).
  110.  
  111. REMEMBER : To use this method of argument passing, origami needs to
  112.            know which history number (OCL-intern) the "arexx" history
  113.            uses. There is no usual way defined in OCL to do this.
  114.            I have changed the source of the amiga keybind binary, so
  115.            all .rc-files compiled on an amiga will contain that number
  116.            and automaticaly define that history. These files will work
  117.            on all other computer systems. If you use a .rc-file from
  118.            another computer system, origami will work, but you can not
  119.            use the argument passing function.
  120.  
  121. Note : keybind passes the history number by using a os-extension of the
  122.        type :
  123.        (os-extension ("AREXXHIST <number-of-history>))
  124.        this line will automatically inserted. If you specify a line with
  125.        the same syntax, origami can use the argument passing function
  126.        even with .rc-files compiled on other systems, but you have to
  127.        know the number (look into the viewrc output ... or guess :-))
  128. }}}
  129.  
  130. {{{  Returning arguments
  131. 6. Returning arguments
  132.  
  133. If you want to return data from inside origami to arexx you have to put
  134. the data on top of the arexx history. Origami will ALWAYS return the
  135. top-most argument. (See example test6.rexx)
  136. }}}
  137.  
  138. {{{  Predefined commands
  139. 7. Predefined commands
  140.  
  141. There are two predefined commands in the current port :
  142. - PUTARG : use this to put an argument on the history stack
  143. - ISDEF : use this function, to determine, if the function used as argument
  144.           is defined.
  145. }}}
  146.  
  147. {{{  What this port can not do. What will be possible in the future ?
  148. 8. What this port can not do. What will be possible in the future ?
  149.  
  150. This is the first release, so there are not many possibilities now.
  151.  
  152. You also can not call any OCL-commands directly. This feature will never
  153. be possible, cause that would result in a much bigger editor (i would have
  154. to include almost the whole keybind executable in the editor). I will
  155. add a command calling exact one OCL-token. This feature should be handled
  156. with care (when ready) due to problems :
  157. - the token code may change in each release !
  158. - arexx sources with tokens are very complicated to read and debug !
  159. - the tokens can only be used to call the lowest functions of OCL
  160.   (call it the OCL-assembler-code). There are only a few checks (origami
  161.   thinks keybinds codes are checked and stored correctly !), so your
  162.   code may crash origami or your machine very easily.
  163. This shows the problems with that feature, so it will not be used much
  164. (i hope).
  165.  
  166. The last feature i want to include in future releases concerns some
  167. build-in commands like PORTNAME (returning the portname), COMMAND
  168. (returning a list of all commands) and maybe some other features.
  169. }}}
  170.  
  171. At the end a last warning : The arexx port is still experimental and may
  172. have some serious bugs (e.g. i didn't try, what happens, when origami
  173. executes a long arexx command and you use the arexx port a second time :-))
  174. Be careful ... thanks
  175.  
  176. Have fun trying
  177. Thomas
  178.